home *** CD-ROM | disk | FTP | other *** search
/ IRIX Base Documentation 2002 November / SGI IRIX Base Documentation 2002 November.iso / usr / share / catman / p_man / cat3dm / midi / mdIntro.z / mdIntro
Encoding:
Text File  |  2002-10-03  |  9.4 KB  |  265 lines
  1.  
  2.  
  3.  
  4. mmmmddddIIIInnnnttttrrrroooo((((3333ddddmmmm))))                                                      mmmmddddIIIInnnnttttrrrroooo((((3333ddddmmmm))))
  5.  
  6.  
  7.  
  8. NNNNAAAAMMMMEEEE
  9.      midi, mdIntro - Introduction to the Silicon Graphics MIDI Library (libmd)
  10.  
  11.  
  12. SSSSYYYYNNNNOOOOPPPPSSSSIIIISSSS
  13.      ####iiiinnnncccclllluuuuddddeeee <<<<ddddmmmmeeeeddddiiiiaaaa////mmmmiiiiddddiiii....hhhh>>>>
  14.  
  15.      ----llllmmmmdddd
  16.  
  17. DDDDEEEESSSSCCCCRRRRIIIIPPPPTTTTIIIIOOOONNNN
  18.      The Silicon Graphics MIDI library (libmd) provides a programming
  19.      interface for applications which wish to receive and transmit messages
  20.      through MIDI interfaces.  MIDI (an acronym for the Musical Instrument
  21.      Digital Interface) is an industry-standard mechanism for connecting to
  22.      and communicating with a variety of devices.  Although it was originally
  23.      designed primarily for use with electronic music instruments (such as
  24.      synthesizers and drum machines), MIDI is now used in conjunction with a
  25.      wide variety of devices, including audio tape decks, theatrical lighting
  26.      systems, and input devices such as button and slider boxes.
  27.  
  28.      The MIDI library makes frequent references to MIDI interfaces. An
  29.      interface provides a source and a destination for MIDI events. Interfaces
  30.      are named with case-insensitive strings when they are created, and these
  31.      names are used throughout the system whenever an interface needs to be
  32.      referenced.  A list of all configured interfaces can be obtained from the
  33.      ssssttttaaaarrrrttttmmmmiiiiddddiiii command or through the use of the mmmmddddGGGGeeeettttNNNNaaaammmmeeee routines.
  34.  
  35.      Interfaces are divided into two classes: physical interfaces and internal
  36.      interfaces.  Physical interfaces are used for connections to the outside
  37.      world and are associated with a physical device to which a physical MIDI
  38.      interface box is connected.  Internal interfaces are the conceptually
  39.      similar to physical interfaces, but they are associated with software
  40.      programs rather than physical devices.  Internal interfaces provide a
  41.      mechanism for "looping back" messages: any messages written to an
  42.      internal interface can be read back from it.  Internal interfaces are
  43.      commonly used in situations where you wish to use MIDI as a form of
  44.      inter-process communication.  For example, the Software Synthesizer (see
  45.      mmmmiiiiddddiiiissssyyyynnnntttthhhh((((1111))))) is able to emulate an external synthesizer by playing notes
  46.      transmitted to it via the "Software Synth" internal interface.
  47.  
  48.      Applications don't need to differentiate between physical and internal
  49.      interfaces; both behave the same way.  If you wish to provide a service
  50.      which receives input or supplies output via an interface in a manner
  51.      similar to  midisynth, you should create a new internal interface for
  52.      your program (see the mmmmddddRRRReeeeggggiiiisssstttteeeerrrr((((3333ddddmmmm)))) man page for more information).
  53.  
  54.      SGI's MIDI implementation allows multiple applications to read and write
  55.      from an interface simultaneously.  If multiple applications are receiving
  56.      events from the same interface, each application will receive its own
  57.      copy of any events which arrive on the interfacet.  If multiple
  58.      applications are sending events to the same interface simultaneously, the
  59.      MIDI library will merge the event streams from the two applications into
  60.  
  61.  
  62.  
  63.                                                                         PPPPaaaaggggeeee 1111
  64.  
  65.  
  66.  
  67.  
  68.  
  69.  
  70. mmmmddddIIIInnnnttttrrrroooo((((3333ddddmmmm))))                                                      mmmmddddIIIInnnnttttrrrroooo((((3333ddddmmmm))))
  71.  
  72.  
  73.  
  74.      a single outgoing event stream. The precise order of the events in the
  75.      merged stream is undefined, but the library guarantees that non-system
  76.      exclusive data will be merged atomically, and that events from the same
  77.      stream will not be reordered.
  78.  
  79.      Applications connect to interfaces through ports.  Ports, which are
  80.      represented by instances of the _M_D_p_o_r_t data type, are an opaque structure
  81.      containing information about the state of MIDI data and timing for a
  82.      connection to a particular interface.  Ports can be opened for either
  83.      input from or output to an interface (via mmmmddddOOOOppppeeeennnnIIIInnnnPPPPoooorrrrtttt((((3333ddddmmmm)))) and
  84.      mmmmddddOOOOppppeeeennnnOOOOuuuuttttPPPPoooorrrrtttt((((3333ddddmmmm)))).
  85.  
  86.      Once the application has opened a port for an interface, it can transmit
  87.      or recieve MIDI events.  The _M_D_e_v_e_n_t data structure is public and is
  88.      defined as:
  89.  
  90.      typedef struct __mdevent {
  91.              char msg[4];                /* channel message data */
  92.              char *sysexmsg;             /* sysex message data */
  93.              unsigned long long stamp;   /* time stamp in nanosecs */
  94.              int msglen;                 /* length of data, sysex only */
  95.      } MDevent;
  96.  
  97.      _s_t_a_m_p is the timestamp of the event.  After an application opens a port,
  98.      it can select one of several stamping modes which control the precise
  99.      format of the stamp (see mmmmddddSSSSeeeettttSSSSttttaaaammmmppppMMMMooooddddeeee).
  100.  
  101.      _m_s_g is an array of characters representing the data of a non-sysexclusive
  102.      message.  The first byte in the array, msg[0], contains the MIDI status
  103.      byte (which in turn encodes the particular command type and, in many
  104.      cases, the channel to which that command applies).  msg[1] and msg[2]
  105.      contain additional parameters which are specific to particular command
  106.      types.  For example, the NOTE ON event takes two additional bytes: the
  107.      note number in msg[1] and the note velocity in msg[2].  The fourth byte
  108.      in the msg array is unused.
  109.  
  110.      _s_y_s_e_x_m_s_g hold a pointer to the system exclusive data block when system
  111.      exclusive data is received or transmitted.
  112.  
  113.      _m_s_g_l_e_n contains a count of the number of bytes in the system exclusive
  114.      block when sysex data is received or transmitted.
  115.  
  116.      The MIDI Library contains a number of functions:
  117.  
  118.  
  119.      mdClosePort(3dm)    - close down any port
  120.  
  121.      mdFree(3dm)         - free storage for libmd
  122.  
  123.      mdGetDivision(3dm)  - gets the divisions per beat or pulses per quarter
  124.                          note
  125.  
  126.  
  127.  
  128.  
  129.                                                                         PPPPaaaaggggeeee 2222
  130.  
  131.  
  132.  
  133.  
  134.  
  135.  
  136. mmmmddddIIIInnnnttttrrrroooo((((3333ddddmmmm))))                                                      mmmmddddIIIInnnnttttrrrroooo((((3333ddddmmmm))))
  137.  
  138.  
  139.  
  140.      mdGetFd(3dm)        - retrieve a file descriptor, for sssseeeelllleeeecccctttt(2)
  141.  
  142.      mdGetName(3dm)      - get the name of a MIDI hardware or virtual device
  143.  
  144.      mdGetStampMode(3dm) - get time stamp mode for a port
  145.  
  146.      mdGetTempo(3dm)     - get tempo, in microseconds per beat
  147.  
  148.      mdInit(3dm)         - initialize MIDI library
  149.  
  150.      mdMalloc(3dm)       - allocate storage for libmd
  151.  
  152.      mdOpenInPort(3dm)   - open an input port
  153.  
  154.      mdOpenOutPort(3dm)  - open an output port
  155.  
  156.      mdPause(3dm)        - discard any events queued on a port and return UST
  157.                          or tick of last event
  158.  
  159.      mdPrintEvent(3dm)   - format MIDI events for human readable printing
  160.  
  161.      mdRegister(3dm)     - register an application with the MIDI system
  162.  
  163.      mdReceive(3dm)      - receive MIDI events
  164.  
  165.      mdSend(3dm)         - send MIDI events
  166.  
  167.      mdSetDivision(3dm)  - gets the divisions per beat
  168.  
  169.      mdSetStampMode(3dm) - set time stamp mode for a port
  170.  
  171.      mdSetStartPoint(3dm)
  172.                          - establish a pairing between a UST and a stamp
  173.  
  174.      mdSetTempo(3dm)     - set tempo, in microseconds per beat
  175.  
  176.      mdTell(3dm)         - return UST or tick of last event sent out
  177.  
  178.      mdTellNow(3dm)      - Return the stamp corresponding to the current time
  179.  
  180.      mdUnRegister(3dm)   - remove an application from the MIDI system
  181.  
  182.      /usr/include/dmedia/midi.h    - MIDI Library header file
  183.      /usr/lib/libmd.so        - MIDI library shared object
  184.      /usr/share/src/dmedia/midi    - MIDI example code
  185.  
  186.      /usr/share/src/dmedia/midi/*  - MIDI Library code examples
  187.  
  188.  
  189.  
  190.  
  191.  
  192.  
  193.  
  194.  
  195.                                                                         PPPPaaaaggggeeee 3333
  196.  
  197.  
  198.  
  199.  
  200.  
  201.  
  202. mmmmddddIIIInnnnttttrrrroooo((((3333ddddmmmm))))                                                      mmmmddddIIIInnnnttttrrrroooo((((3333ddddmmmm))))
  203.  
  204.  
  205.  
  206. SEE ALSO
  207.      MIDI 1.0 Detailed Specification
  208.      Standard MIDI File Specification 1.0
  209.      (both available from the MIDI manufacturer's association)
  210.  
  211.  
  212.  
  213.  
  214.  
  215.  
  216.  
  217.  
  218.  
  219.  
  220.  
  221.  
  222.  
  223.  
  224.  
  225.  
  226.  
  227.  
  228.  
  229.  
  230.  
  231.  
  232.  
  233.  
  234.  
  235.  
  236.  
  237.  
  238.  
  239.  
  240.  
  241.  
  242.  
  243.  
  244.  
  245.  
  246.  
  247.  
  248.  
  249.  
  250.  
  251.  
  252.  
  253.  
  254.  
  255.  
  256.  
  257.  
  258.  
  259.  
  260.  
  261.                                                                         PPPPaaaaggggeeee 4444
  262.  
  263.  
  264.  
  265.